import PlatformsList from '../../components/PlatformsList/PlatformsList.tsx';

# Events

This page lists all available callbacks for handling player notifications.

## Details

### `onAudioBecomingNoisy`

<PlatformsList types={['Android', 'iOS']} />

Triggered when audio output changes (e.g., switching from headphones to speakers). It's recommended to pause the media when this event occurs.

**Payload:** _none_

---

### `onAudioFocusChanged`

<PlatformsList types={['Android']} />

Called when audio focus is gained or lost.

**Payload:**
| Property       | Type    | Description                                  |
|---------------|--------|----------------------------------------------|
| hasAudioFocus | boolean | `true` if media has audio focus, `false` otherwise |

**Example:**
```javascript
{
  hasAudioFocus: true
}
```

---

### `onAudioTracks`

<PlatformsList types={['Android', 'iOS']} />

Triggered when available audio tracks change.

**Payload:** _Array of objects with track details_

| Property | Type    | Description                                                                 |
|----------|--------|-----------------------------------------------------------------------------|
| index    | number  | Internal track ID                                                          |
| title    | string  | Descriptive track name                                                     |
| language | string  | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code |
| bitrate  | number  | Track bitrate                                                              |
| type     | string  | Track MIME type                                                            |
| selected | boolean | `true` if track is currently playing                                       |

**Example:**
```javascript
{
  audioTracks: [
    { language: 'es', title: 'Spanish', type: 'audio/mpeg', index: 0, selected: true },
    { language: 'en', title: 'English', type: 'audio/mpeg', index: 1 }
  ]
}
```

---

### `onBandwidthUpdate`

<PlatformsList types={['Android', 'iOS']} />

Called when available bandwidth changes.

**Payload:**
| Property | Type   | Description                                   |
|----------|--------|-----------------------------------------------|
| bitrate  | number | Estimated bitrate in bits/sec                |
| width    | number | Video width (Android only)                   |
| height   | number | Video height (Android only)                  |
| trackId  | string | Video track ID (Android only)                |

**Example (iOS):**
```javascript
{
  bitrate: 1000000
}
```

**Example (Android):**
```javascript
{
  bitrate: 1000000,
  width: 1920,
  height: 1080,
  trackId: 'some-track-id'
}
```

> **Note:** On Android, set the [`reportBandwidth`](#reportbandwidth) prop to enable this event.

---

### `onBuffer`

<PlatformsList types={['Android', 'iOS', 'web']} />

Triggered when buffering starts or stops.

**Payload:**
| Property    | Type    | Description                     |
|------------|--------|---------------------------------|
| isBuffering | boolean | `true` if buffering is active  |

**Example:**
```javascript
{
  isBuffering: true
}
```

---

### `onControlsVisibilityChange`

<PlatformsList types={['Android']} />

Triggered when the video player controls become visible or hidden.

**Payload:**
| Property  | Type    | Description                         |
|----------|--------|-------------------------------------|
| isVisible | boolean | `true` if controls are visible |

**Example:**
```javascript
{
  isVisible: true
}
```

---

### `onEnd`

<PlatformsList types={['All']} />

Triggered when the media reaches the end.

**Payload:** _none_

---

### `onError`

<PlatformsList types={['All']} />

Called when a playback error occurs.

**Payload:**
| Property | Type   | Description               |
|---------|--------|---------------------------|
| error   | object | Error details              |

---

### `onExternalPlaybackChange`

<PlatformsList types={['iOS']} />

Called when external playback mode changes (e.g., Apple TV connection/disconnection).

**Payload:**
| Property                 | Type    | Description                                |
|-------------------------|--------|--------------------------------------------|
| isExternalPlaybackActive | boolean | `true` if external playback is active |

**Example:**
```javascript
{
  isExternalPlaybackActive: true
}
```

---

### `onFullscreenPlayerWillPresent`

<PlatformsList types={['Android', 'iOS', 'visionOS']} />

Called before entering fullscreen mode.

**Payload:** _none_

---

### `onFullscreenPlayerDidPresent`

<PlatformsList types={['Android', 'iOS', 'visionOS']} />

Called when fullscreen mode is active.

**Payload:** _none_

---

### `onFullscreenPlayerWillDismiss`

<PlatformsList types={['Android', 'iOS', 'visionOS']} />

Called before exiting fullscreen mode.

**Payload:** _none_

---

### `onFullscreenPlayerDidDismiss`

<PlatformsList types={['Android', 'iOS', 'visionOS']} />

Called when fullscreen mode is exited.

**Payload:** _none_

---

### `onLoad`

<PlatformsList types={['All']} />

Triggered when the media is loaded and ready to play.

### Payload:

| Property    | Type   | Description                                                                                                                                                                                                                                                                                                                                                        |
|-------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| currentTime | number | Time in seconds where the media will start                                                                                                                                                                                                                                                                                                                         |
| duration    | number | Length of the media in seconds                                                                                                                                                                                                                                                                                                                                     |
| naturalSize | object | Properties:<br/> &ensp; width - Width in pixels that the video was encoded at<br/> &ensp; height - Height in pixels that the video was encoded at<br/> &ensp; orientation - "portrait", "landscape" or "square"                                                                                                                                                                  |
| audioTracks | array  | An array of audio track info objects with the following properties:<br/> &ensp; index - Index number<br/> &ensp; title - Description of the track<br/> &ensp; language - 2 letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or 3 letter [ISO639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) language code<br/> &ensp; type - Mime type of track |
| textTracks  | array  | An array of text track info objects with the following properties:<br/> &ensp; index - Index number<br/> &ensp; title - Description of the track<br/> &ensp; language - 2 letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) or 3 letter [ISO 639-2](https://en.wikipedia.org/wiki/List_of_ISO_639-2_codes) language code<br/> &ensp; type - Mime type of track |
| videoTracks | array  | An array of video track info objects with the following properties:<br/> &ensp; trackId - ID for the track<br/> &ensp; bitrate - Bit rate in bits per second<br/> &ensp; codecs - Comma separated list of codecs<br/> &ensp; height - Height of the video<br/> &ensp; width - Width of the video                                                                                           |
| trackId     | string | Provide key information about the video track, typically including: `Resolution`, `Bitrate`.                                                                                                                                                                                                                                                                                                                                                |

**Example:**

```js
{
  canPlaySlowForward: true,
  canPlayReverse: false,
  canPlaySlowReverse: false,
  canPlayFastForward: false,
  canStepForward: false,
  canStepBackward: false,
  currentTime: 0,
  duration: 5910.208984375,
  naturalSize: {
     height: 1080
     orientation: 'landscape'
     width: '1920'
  },
  audioTracks: [
    { language: 'es', title: 'Spanish', type: 'audio/mpeg', index: 0 },
    { language: 'en', title: 'English', type: 'audio/mpeg', index: 1 }
  ],
  textTracks: [
    { title: '#1 French', language: 'fr', index: 0, type: 'text/vtt' },
    { title: '#2 English CC', language: 'en', index: 1, type: 'text/vtt' },
    { title: '#3 English Director Commentary', language: 'en', index: 2, type: 'text/vtt' }
  ],
  videoTracks: [
    { index: 0, bitrate: 3987904, codecs: "avc1.640028", height: 720, trackId: "f1-v1-x3", width: 1280 },
    { index: 1, bitrate: 7981888, codecs: "avc1.640028", height: 1080, trackId: "f2-v1-x3", width: 1920 },
    { index: 2, bitrate: 1994979, codecs: "avc1.4d401f", height: 480, trackId: "f3-v1-x3", width: 848 }
  ],
  trackId: "720p 2400kbps",
}
```

> **Note:** `audioTracks`, `textTracks`, and `videoTracks` are not available on the web.

---

### `onLoadStart`

<PlatformsList types={['All']} />

Triggered when media starts loading.

**Payload:**
| Property  | Type    | Description                           |
|----------|--------|-------------------------------------|
| isNetwork | boolean | `true` if media is loaded from a network |
| type      | string  | Media type (not available on Windows) |
| uri       | string  | Media source URI (not available on Windows) |

**Example:**
```javascript
{
  isNetwork: true,
  type: '',
  uri: 'https://example.com/video.mp4'
}
```

---

### `onPlaybackStateChanged`

<PlatformsList types={['Android', 'iOS', 'visionOS', 'web']} />

Triggered when playback state changes.

**Payload:**
| Property  | Type    | Description                         |
|----------|--------|-------------------------------------|
| isPlaying | boolean | `true` if media is playing        |
| isSeeking | boolean | `true` if seeking is in progress |

**Example:**
```javascript
{
  isPlaying: true,
  isSeeking: false
}
```

---

### `onPictureInPictureStatusChanged`

<PlatformsList types={['iOS', 'Android', 'web']} />

Triggered when Picture-in-Picture (PiP) mode is activated or deactivated.

**Payload:**
| Property  | Type    | Description                        |
|----------|--------|----------------------------------|
| isActive | boolean | `true` if PiP mode is active |

**Example:**
```javascript
{
  isActive: true
}
```

---

### `onPlaybackRateChange`

<PlatformsList types={['All']} />

Triggered when playback speed changes.

**Payload:**
| Property     | Type   | Description                     |
|-------------|--------|---------------------------------|
| playbackRate | number | `0` (paused), `1` (normal speed), other values indicate speed changes |

**Example:**
```javascript
{
  playbackRate: 0  // indicates paused
}
```

---

### `onProgress`

<PlatformsList types={['All']} />

Triggered every `progressUpdateInterval` milliseconds, providing information about the current playback position.

**Payload:**
| Property         | Type   | Description                                                             |
|----------------|--------|-------------------------------------------------------------------------|
| currentTime      | number | Current playback position (seconds)                                   |
| playableDuration | number | Duration that can be played using only the buffer (seconds)          |
| seekableDuration | number | Duration that can be seeked to (usually the total length of the media) |

**Example:**
```javascript
{
  currentTime: 5.2,
  playableDuration: 34.6,
  seekableDuration: 888
}
```

---

### `onReadyForDisplay`

<PlatformsList types={['Android', 'iOS', 'Web']} />

Triggered when the first video frame is ready to be displayed. This is when the poster is removed.

**Payload:** _none_

- iOS: [`readyForDisplay`](https://developer.apple.com/documentation/avkit/avplayerviewcontroller/1615830-readyfordisplay?language=objc)
- Android: [`STATE_READY`](https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/Player.html#STATE_READY)

---

### `onReceiveAdEvent`

<PlatformsList types={['Android', 'iOS']} />

Triggered when an AdEvent is received from the IMA SDK.

Enum `AdEvent` possible values for [Android](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side/reference/js/google.ima.AdEvent) and [iOS](https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side/reference/Enums/IMAAdEventType):

<details>
  <summary>AdEvent</summary>

  | Event                      | Platform     | Description                                                                                                                                                                                                 |
  | -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `AD_BREAK_ENDED`           | iOS          | Fired the first time each ad break ends. Applications must reenable seeking when this occurs (only used for dynamic ad insertion).                                                                          |
  | `AD_BREAK_READY`           | Android, iOS | Fires when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false.                                                                                                                    |
  | `AD_BREAK_STARTED`         | iOS          | Fired first time each ad break begins playback. If an ad break is watched subsequent times this will not be fired. Applications must disable seeking when this occurs (only used for dynamic ad insertion). |
  | `AD_BUFFERING`             | Android      | Fires when the ad has stalled playback to buffer.                                                                                                                                                           |
  | `AD_CAN_PLAY`              | Android      | Fires when the ad is ready to play without buffering, either at the beginning of the ad or after buffering completes.                                                                                       |
  | `AD_METADATA`              | Android      | Fires when an ads list is loaded.                                                                                                                                                                           |
  | `AD_PERIOD_ENDED`          | iOS          | Fired every time the stream switches from advertising or slate to content. This will be fired even when an ad is played a second time or when seeking into an ad (only used for dynamic ad insertion).      |
  | `AD_PERIOD_STARTED`        | iOS          | Fired every time the stream switches from content to advertising or slate. This will be fired even when an ad is played a second time or when seeking into an ad (only used for dynamic ad insertion).      |
  | `AD_PROGRESS`              | Android      | Fires when the ad's current time value changes. The event `data` will be populated with an AdProgressData object.                                                                                           |
  | `ALL_ADS_COMPLETED`        | Android, iOS | Fires when the ads manager is done playing all the valid ads in the ads response, or when the response doesn't return any valid ads.                                                                        |
  | `CLICK`                    | Android, iOS | Fires when the ad is clicked.                                                                                                                                                                               |
  | `COMPLETED`                | Android, iOS | Fires when the ad completes playing.                                                                                                                                                                        |
  | `CONTENT_PAUSE_REQUESTED`  | Android      | Fires when content should be paused. This usually happens right before an ad is about to cover the content.                                                                                                 |
  | `CONTENT_RESUME_REQUESTED` | Android      | Fires when content should be resumed. This usually happens when an ad finishes or collapses.                                                                                                                |
  | `CUEPOINTS_CHANGED`        | iOS          | Cuepoints changed for VOD stream (only used for dynamic ad insertion).                                                                                                                                      |
  | `DURATION_CHANGE`          | Android      | Fires when the ad's duration changes.                                                                                                                                                                       |
  | `ERROR`                    | Android, iOS | Fires when an error occurred while loading the ad and prevent it from playing.                                                                                                                              |
  | `FIRST_QUARTILE`           | Android, iOS | Fires when the ad playhead crosses first quartile.                                                                                                                                                          |
  | `IMPRESSION`               | Android      | Fires when the impression URL has been pinged.                                                                                                                                                              |
  | `INTERACTION`              | Android      | Fires when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data.                                                                                        |
  | `LINEAR_CHANGED`           | Android      | Fires when the displayed ad changes from linear to nonlinear, or the reverse.                                                                                                                               |
  | `LOADED`                   | Android, iOS | Fires when ad data is available.                                                                                                                                                                            |
  | `LOG`                      | Android, iOS | Fires when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation.                              |
  | `MIDPOINT`                 | Android, iOS | Fires when the ad playhead crosses midpoint.                                                                                                                                                                |
  | `PAUSED`                   | Android, iOS | Fires when the ad is paused.                                                                                                                                                                                |
  | `RESUMED`                  | Android, iOS | Fires when the ad is resumed.                                                                                                                                                                               |
  | `SKIPPABLE_STATE_CHANGED`  | Android      | Fires when the displayed ads skippable state is changed.                                                                                                                                                    |
  | `SKIPPED`                  | Android, iOS | Fires when the ad is skipped by the user.                                                                                                                                                                   |
  | `STARTED`                  | Android, iOS | Fires when the ad starts playing.                                                                                                                                                                           |
  | `STREAM_LOADED`            | iOS          | Stream request has loaded (only used for dynamic ad insertion).                                                                                                                                             |
  | `TAPPED`                   | iOS          | Fires when the ad is tapped.                                                                                                                                                                                |
  | `THIRD_QUARTILE`           | Android, iOS | Fires when the ad playhead crosses third quartile.                                                                                                                                                          |
  | `UNKNOWN`                  | iOS          | An unknown event has fired                                                                                                                                                                                  |
  | `USER_CLOSE`               | Android      | Fires when the ad is closed by the user.                                                                                                                                                                    |
  | `VIDEO_CLICKED`            | Android      | Fires when the non-clickthrough portion of a video ad is clicked.                                                                                                                                           |
  | `VIDEO_ICON_CLICKED`       | Android      | Fires when a user clicks a video icon.                                                                                                                                                                      |
  | `VOLUME_CHANGED`           | Android      | Fires when the ad volume has changed.                                                                                                                                                                       |
  | `VOLUME_MUTED`             | Android      | Fires when the ad volume has been muted.                                                                                                                                                                    |

</details>

**Payload:**
| Property | Type                                      | Description           |
|----------|-----------------------------------------|---------------------|
| event    | AdEvent                                   | The ad event received |
| data     | Record&lt;string, string&gt; \| undefined | Additional ad event data |

**Example:**
```json
{
  "data": {
    "key": "value"
  },
  "event": "LOG"
}
```

---

### `onRestoreUserInterfaceForPictureInPictureStop`

<PlatformsList types={['iOS', 'visionOS']} />

Corresponds to Apple's [`restoreUserInterfaceForPictureInPictureStopWithCompletionHandler`](https://developer.apple.com/documentation/avkit/avpictureinpicturecontrollerdelegate/1614703-pictureinpicturecontroller?language=objc).
Call `restoreUserInterfaceForPictureInPictureStopCompleted` inside this function when the UI is restored.

**Payload:** _none_

---

### `onSeek`

<PlatformsList types={['Android', 'iOS', 'Windows UWP', 'web']} />

Triggered when a seek operation completes.

**Payload:**
| Property    | Type   | Description                     |
|------------|--------|---------------------------------|
| currentTime | number | Current time after seeking     |
| seekTime    | number | Requested seek time            |

**Example:**
```javascript
{
  currentTime: 100.5,
  seekTime: 100
}
```

> **Note:** On iOS, this callback is not reported when native controls are enabled.

---

### `onTimedMetadata`

<PlatformsList types={['Android', 'iOS', 'visionOS']} />

Triggered when timed metadata is available.

**Payload:**
| Property | Type  | Description               |
|----------|------|--------------------------|
| metadata | array | Array of metadata objects |

**Example:**
```javascript
{
  metadata: [
    { value: 'Streaming Encoder', identifier: 'TRSN' },
    { value: 'Internet Stream', identifier: 'TRSO' },
    { value: 'Any Time You Like', identifier: 'TIT2' }
  ]
}
```

---

### `onTextTrackDataChanged`

<PlatformsList types={['Android', 'iOS']} />

Triggered when new subtitle data becomes available.

**Payload:**
| Property         | Type     | Description                                       |
|----------------|--------|--------------------------------------------------|
| subtitleTracks | string  | The subtitle text content in a compatible format |

**Example:**
```javascript
{
  subtitleTracks: "This blade has a dark past."
}
```

---

### `onTextTracks`

<PlatformsList types={['Android', 'iOS']} />

Triggered when available text (subtitle) tracks change.

**Payload:**
| Property | Type    | Description                                                                                                  |
|----------|--------|--------------------------------------------------------------------------------------------------------------|
| index    | number  | Internal track ID                                                                                           |
| title    | string  | Track name                                                                                                  |
| language | string  | 2 letter [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code                           |
| type     | string  | Track MIME type (_VTT_, _SRT_, _TTML_)                                                                      |
| selected | boolean | `true` if the track is currently playing                                                                   |

**Example:**
```javascript
{
  textTracks: [
    {
      index: 0,
      title: 'English Subtitles',
      type: 'vtt',
      selected: true
    }
  ]
}
```

---

### `onVideoTracks`

<PlatformsList types={['Android']} />

Triggered when video tracks change.

**Payload:**
| Property | Type    | Description                       |
|----------|---------|-----------------------------------|
| index    | number  | Track index                       |
| trackId  | string  | Internal track ID                 |
| codecs   | string  | Codec type                        |
| width    | number  | Video width                       |
| height   | number  | Video height                      |
| bitrate  | number  | Track bitrate (bps)               |
| selected | boolean | `true` if the track is playing    |
| rotation | number  | Rotation angle (0, 90, 180, 270)  |

**Example:**
```javascript
{
  videoTracks: [
    {
      index: 0,
      trackId: "1",
      codecs: "video/mp4",
      width: 1920,
      height: 1080,
      bitrate: 5000000,
      selected: true,
      rotation: 0
    }
  ]
}
```

---

### `onVolumeChange`

<PlatformsList types={['Android', 'iOS', 'visionOS', 'web']} />

Triggered when the player volume changes.

> **Note:** This event applies to the player's volume, not the device's system volume.

**Payload:**
| Property | Type   | Description                       |
|----------|--------|---------------------------------|
| volume   | number | Volume level (0 to 1)          |

**Example:**
```javascript
{
  volume: 0.5
}
```
